home *** CD-ROM | disk | FTP | other *** search
/ Pluspack 1 / Caligari Corporation Pluspack1 1998.iso / TSX_SDK / tsxINC / Readme.txt < prev    next >
Encoding:
Text File  |  1998-01-28  |  9.7 KB  |  259 lines
  1. ------------------------------------------------------------------------------
  2.         Overview of the trueSpace extensions (TSX) API
  3.  
  4.                         Release 3.0
  5.                  Apr 11, 1997
  6.  
  7.                Copyright Caligari Corp.
  8. ------------------------------------------------------------------------------
  9.  
  10.  
  11.  
  12. 1.    INTRODUCTION
  13. ~~~~~~~~~~~~~~~~~~~~
  14.  
  15. The trueSpace Extension (TSX) Interface is a mechanism by which developers
  16. outside Caligari can add functionality to trueSpace.  This document
  17. describes the latest release of the TSX API (numbered to coincide with
  18. trueSpace release numbers).
  19.  
  20.  
  21.  
  22. 2.    PLATFORM
  23. ~~~~~~~~~~~~~~~~
  24.  
  25. At present, trueSpace extensions are only supported on the Windows
  26. platforms.  A trueSpace Extension (TSX) is a dynamically linked library
  27. (DLL) loaded by trueSpace at run-time.  Like trueSpace, TSXs must be WIN32
  28. applications.  If a TSX uses MFC, its installation procedure must be
  29. responsible for ensuring the presence of the correct versions of any needed
  30. MFC DLLs.
  31.  
  32. While TSXs may be developed using any compiler, primary support at present
  33. is for Microsoft Visual C++ 4.1.  The API may also be usable in "C" mode,
  34. but is not currently supported.
  35.  
  36.  
  37.  
  38.  
  39. 3.    COMPILING A TSX
  40. ~~~~~~~~~~~~~~~~~~~~~~~
  41.  
  42. The TSX API is made available in the form of a set of "header" files and
  43. an "import" library that together define the "exported" items accessible in
  44. a running trueSpace.  TrueSpace itself consists of an executable
  45. (truespac.exe) and a dynamically linked library (tsxapi.dll).  The TSX API
  46. functions are exported from the DLL.
  47.  
  48. List of files in the TSX API:
  49.  
  50.    Readme.txt    .. This file
  51.  
  52.    tsxapi.lib    .. The import library. Specifies dynamic linkage with
  53.            tsxapi.dll .
  54.  
  55.    tsxapi.dll    .. Standard DLL part of trueSpace.
  56.  
  57.     Header files:
  58.  
  59.    tsx.h    .. Single header for including all other header files.
  60.  
  61.     The following header files may also be included individually in
  62.     your source code:
  63.  
  64.    tsximp.h    .. This must be included before all other TSX headers.
  65.    tsxapi.h    .. Includes all the API module headers.
  66.    tsxErr.h    .. Error codes.
  67.  
  68.     Individual API module headers:
  69.  
  70.    tsxplug.h    .. User interface and TSX installation API.
  71.  
  72.    tsxAnim.h    .. Animation module.
  73.    tsxAView.h    .. Active-Viewport module.
  74.    tsxCamra.h    .. Cameras.
  75.    tsxGeom.h    .. Basic geometry functions.
  76.    tsxGNode.h    .. Geometric Nodes.
  77.    tsxGroup.h    .. Group Nodes.
  78.    tsxLight.h    .. Lights.
  79.    tsxMatrl.h    .. Materials, used for painting objects.
  80.    tsxMisc.h    .. Miscellaneous items.
  81.    tsxMNode.h    .. Model Nodes.
  82.    tsxMouse.h    .. Mouse interaction module.
  83.    tsxPolyh.h    .. Polyhedra.
  84.    tsxScene.h    .. Scene Node.
  85.    tsxSelec.h    .. Object Selection module.
  86.    tsxSobj.h    .. Common Abstract Object.
  87.    tsxTypes.h    .. All Common type definitions.
  88.  
  89.  
  90.  
  91.  
  92. 4.    INTERFACING WITH trueSPACE
  93. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  94.  
  95. Typically, a user will load a TSX from within trueSpace by selecting the
  96. appropriate DLL through a File-Open dialog.  Each loaded TSX will be
  97. assigned to a button in trueSpace's interface.  The TSX will supply a Bitmap
  98. and a String resource to serve as the button's icon and help message.  Upto
  99. eight TSXs may be installed in trueSpace at any given time.
  100.  
  101. Every TSX must implement the following four functions (see tsxplug.h):
  102.  
  103.     void tsxGetData( tsxData* tsx_data, int tsxid );
  104.     Called once upon loading, to access basic information about the
  105.     TSX, including the icon and help message resources.  Assigns each
  106.     extension installation a unique id (tsxid).
  107.  
  108.     int tsxOnLeftClick(void);
  109.     Called when the user Left-Clicks on the TSX button.  Primary entry
  110.     point for invoking the TSX's functionality.  The TSX may perform a
  111.     "one-shot" action (e.g. move an object), or stay active for
  112.     continued interaction with the user (e.g. for drawing).  If the
  113.     eXtension wants to stay active, this function must return 
  114.     `tsxPLUG_STAYON'.  This will turn the eXtension's button "ON".
  115.     Subsequent click on this button will result in a call to the
  116.     function `tsxDeactivate', and the eXtension will be deactivated.
  117.     The same happens when the user selects some other tool through
  118.     trueSpace's interface.  Some selected tools (like navigation and
  119.     rendering) are allowed to operate while an eXtension is active.
  120.     For one-shot operations, or where the eXtension does not want to
  121.     have `tsxDeactivate' invoked as described above, `tsxOnLeftClick'
  122.     must return tsxPLUG_DONE.  The eXtension is then considered to be
  123.     active only while executing `tsxOnLeftClick'.  The main purpose
  124.     of this managing an eXtension's "active" status is for allowing an
  125.     eXtension to "switch off" (and perhaps perform some clean-up operation)
  126.     when some other tool is selected.  In addition, an eXtension may
  127.     install callbacks only while it is active.
  128.  
  129.     void tsxDeactivate(void);
  130.     When an eXtension requests it be allowed to stay active (see
  131.     above), this function is called to deactivate it.  This happens when
  132.     some other editing tool is selected, when trueSpace goes out of
  133.     edit mode and into browse mode, or when the user tries to install
  134.     another eXtension.  Certain tools are allowed to operate while an
  135.     eXtension is active.  These include all navigation and most
  136.     rendering operations.
  137.  
  138.     void tsxOnRightClick(void);
  139.     Called when the user Right-Clicks on the TSX button.  Primarily used
  140.     to display a parameter dialog or an "About" dialog.
  141.  
  142. In the trueSpace user-interface paradigm, a TSX installs a tool on a panel
  143. button.  The tool is invoked, like all other tools in trueSpace, when the
  144. user Left-Clicks the TSX's button.  A Right-Click on the button should
  145. display a parameter dialog for the TSX, if any, or an "About" dialog
  146. describing the TSX.
  147.  
  148. TSXs are responsible for implementing and managing their own windows.  For
  149. example, a TSX may use MFC to manage its interface.  In the final release,
  150. the TSXAPI will allow a TSX to install the mouse for user interaction.
  151. trueSpace will then forward mouse action messages to the TSX.  When some
  152. other tool is selected by the user, trueSpace will tell the TSX that it is
  153. being deactivated.
  154.  
  155. The trueSpace eXtension API allows the installation of some callbacks.
  156. These can only be done while an eXtension is "active".
  157.  
  158. An extension may test whether it is compatible with a copy of trueSpace
  159. by checking the version number of the TSX API in that copy of trueSpace
  160. (see tsxMisc.h).
  161.  
  162.  
  163.  
  164.  
  165. 5.    OVERVIEW of the API
  166. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  167.  
  168. Please use the documentation in the header files and the provided sample
  169. extensions as primary reference.  A brief overview is given below.
  170.  
  171.     The Scene Graph
  172.  
  173. Objects in a trueSpace scene are arranged in a tree-shaped hierarchy, with a
  174. permanent Scene node (tsxSCENE) at the top, and geometric nodes and leaves
  175. (the abstract type tsxGNODE).  The most important objects that appear in the
  176. Scene Graph are Lights (tsxLIGHT), Cameras (tsxCAMERA), Polyhedra
  177. (tsxPOLYHEDRON), and Groups (tsxGROUP) used to build hierarchical objects.
  178. All these are represented in the API as structures, defined in tsxTypes.h.
  179.  
  180. Object hierarchy supported in this release:
  181.  
  182.   tsxSOBJ
  183.   +--- tsxMATERIAL
  184.   +--- tsxSCENE
  185.   +--- tsxGNODE
  186.        +--- tsxCAMERA
  187.        +--- tsxLIGHT
  188.        +--- tsxMNODE
  189.             +--- tsxPOLYHEDRON
  190.         +--- tsxGROUP
  191.         +--- tsxLODGROUP
  192.         +--- tsxMBALLOBJ
  193.  
  194. The actual structure of the scene graph has each parent node pointing
  195. to its first child, and each child pointing to its next sibling.  From
  196. the SCENE node, use `tsxSceneGetFirstNode()' to get to the first
  197. GNODE (see tsxScene.h).  From there, use `tsxGNodeGetNext()' to get to
  198. other GNODEs at the top level in the scene graph.  Similarly, use
  199. `tsxGNodeGetFirstChild()' to get to the first subNode of a GROUP or LOD
  200. node, and then use `tsxGNodeGetNext()' to get to other children of the
  201. same GROUP/LOD node (see tsxGNode.h).
  202.  
  203. Please see the individual header files for more documentation on each
  204. of these object types.
  205.  
  206. NOTE: 
  207.  There is very limited support for the types tsxLODGROUP and tsxMBALLOBJ.
  208.  
  209.  
  210.     Brief Guide to the Header files 
  211.     (see also Section 3 on Compiling, above)
  212.  
  213.    tsxplug.h    .. User interface and TSX installation API.
  214.     This contains all the information needed to make trueSpace correctly
  215.     install and invoke the extension.
  216.  
  217.    tsxMisc.h    .. Miscellaneous items,
  218.     including checking TSX API's version number.
  219.  
  220.    tsxTypes.h    .. All Common type definitions.
  221.     Start your familiarization with the TSX API with this header.
  222.  
  223.    tsxSobj.h    .. Common Abstract Object.
  224.    tsxScene.h    .. Scene Node.
  225.    tsxGNode.h    .. Geometric Nodes.
  226.    tsxCamra.h    .. Cameras.
  227.    tsxLight.h    .. Lights.
  228.    tsxMNode.h    .. Model Nodes.
  229.    tsxGroup.h    .. Group Nodes.
  230.    tsxPolyh.h    .. Polyhedra.
  231.     These header files describe the different object types that
  232.     form a scene, as mentioned above.
  233.  
  234.    tsxMatrl.h    .. Materials.
  235.     Every polyhedron has one or more materials defining various visible
  236.     attributes like color, texture, bumps.
  237.  
  238.    tsxAnim.h    .. Animation module.
  239.     This file describes trueSpace's animation interface.
  240.  
  241.    tsxSelec.h    .. Object Selection module.
  242.     This describes the interface for accessing the currently
  243.     selected object, and changing that selection.
  244.  
  245.    tsxAView.h    .. Active-Viewport module.
  246.     This describes the interface for manipualting the active view
  247.     of the scene, e.g. moving the viewpoint.
  248.  
  249.    tsxMouse.h    .. Mouse interaction module.
  250.     Together with functions declared in "tsxAView.h", this
  251.     interface can be used to interact with the mouse, and pick
  252.     objects in the scene (lower level than tsxSelec.h).
  253.  
  254.    tsxGeom.h    .. Basic geometry functions.
  255.     This lists some functions for performing basic geometric
  256.     manipulations.
  257.  
  258. ------------------------------------------------------------------------------
  259.